<HTML><HEAD><TITLE>local shelf(++Name, +Init)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Non-logical Variables, Arrays, Bags, Shelves and Stores</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>local shelf(++Name, +Init)</H1>
Create a named shelf object which can store data across failures
<DL>
<DT><EM>Name</EM></DT>
<DD>An atom, or an atom/integer structure
</DD>
<DT><EM>Init</EM></DT>
<DD>A structure
</DD>
</DL>
<H2>Description</H2>
    	This creates a 'shelf' object which can be used to store
	information across failures.  A typical application is counters
	for statistics, etc.
<P>
	A shelf is an object with multiple slots whose contents survive
	backtracking. The content of each slot can be set and retrieved
	individually, or the whole shelf can be retrieved as a term.
<P>
	Shelves can be referred to either by handle or by name. Whenever
	possible, handles should be used, because this naturally leads to
	robust, reentrant code, and avoids the danger of memory leaks.
	See shelf_create/2,3 for how to create shelves with a handle.
<P>
	Named shelves are identified by a functor. This is usually simply
	an atom, but in general it can be name/arity pair.
<P>
	When named shelves are used, the visibility of the shelf name is
	local to the module where it was created. A named shelf never
	disappears, therefore, in order to free the associated memory,
	its contents should be erased when no longer needed.
<P>
	Duplicate shelf declarations are silently ignored.
    
<H3>Modes and Determinism</H3><UL>
<LI>shelf(++, +) is det
</UL>
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>Name or Init is uninstantiated
<DT><EM>(5) type error </EM>
<DD>Init is not a structure
<DT><EM>(5) type error </EM>
<DD>Name is neither an atom nor an atom/integer structure
</DL>
<H2>Examples</H2>
<PRE>

    % A store with the simple, atomic name 'counters'

    :- local shelf(counters, count(0,0,0)).

    main :-
	shelf_get(counters,1,N0), N1 is N0+1, shelf_set(counters,1,N1),
	printf("main has been called %d times%n", [N1]).
    </PRE>
<H2>See Also</H2>
<A HREF="../../kernel/storage/shelf_create-2.html">shelf_create / 2</A>, <A HREF="../../kernel/storage/shelf_create-3.html">shelf_create / 3</A>, <A HREF="../../kernel/modules/local-1.html">local / 1</A>, <A HREF="../../kernel/storage/shelf_set-3.html">shelf_set / 3</A>, <A HREF="../../kernel/storage/shelf_get-3.html">shelf_get / 3</A>, <A HREF="../../kernel/storage/store_delete-2.html">store_delete / 2</A>, <A HREF="../../kernel/storage/store_contains-2.html">store_contains / 2</A>, <A HREF="../../kernel/storage/stored_keys-2.html">stored_keys / 2</A>, <A HREF="../../kernel/storage/stored_keys_and_values-2.html">stored_keys_and_values / 2</A>, <A HREF="../../kernel/storage/store_erase-1.html">store_erase / 1</A>, <A HREF="../../kernel/storage/store_count-2.html">store_count / 2</A>
</BODY></HTML>
